Once you've got a library that you'd like to share with the world, it's time to
publish it on [crates.io]! Publishing a crate is when a specific
-version is uploaded to be hosted on crates.io.
+version is uploaded to be hosted on [crates.io].
Take care when publishing a crate, because a publish is **permanent**. The
version can never be overwritten, and the code cannot be deleted. There is no
# Before publishing a new crate
-Keep in mind that crate names on crates.io are allocated on a first-come-first-
+Keep in mind that crate names on [crates.io] are allocated on a first-come-first-
serve basis. Once a crate name is taken, it cannot be used for another crate.
## Packaging a crate
The next step is to package up your crate into a format that can be uploaded to
-crates.io. For this we’ll use the `cargo package` subcommand. This will take
+[crates.io]. For this we’ll use the `cargo package` subcommand. This will take
our entire crate and package it all up into a `*.crate` file in the
`target/package` directory.
## Uploading the crate
Now that we’ve got a `*.crate` file ready to go, it can be uploaded to
-crates.io with the `cargo publish` command. And that’s it, you’ve now published
+[crates.io] with the `cargo publish` command. And that’s it, you’ve now published
your first crate!
```notrust
# Managing a crates.io-based crate
Management of crates is primarily done through the command line `cargo` tool
-rather than the crates.io web interface. For this, there are a few subcommands
+rather than the [crates.io] web interface. For this, there are a few subcommands
to manage a crate.
## `cargo yank`
The semantics of a yanked version are that no new dependencies can be created
against that version, but all existing dependencies continue to work. One of the
-major goals of crates.io is to act as a permanent archive of crates that does
+major goals of [crates.io] is to act as a permanent archive of crates that does
not change over time, and allowing deletion of a version would go against this
goal. Essentially a yank means that all projects with a `Cargo.lock` will not
break, while any future `Cargo.lock` files generated will not list the yanked
of the crate, they have the ability to add or remove owners, *including* the
owner that made *them* an owner. Needless to say, you shouldn’t make people you
don’t fully trust into a named owner. In order to become a named owner, a user
-must have logged into crates.io previously.
+must have logged into [crates.io] previously.
If a team name is given to `--add`, that team becomes a “team” owner, with
restricted right to the crate. While they have permission to publish or yank
is likely for you to encounter the following message when working with them:
> It looks like you don’t have permission to query a necessary property from
-GitHub to complete this request. You may need to re-authenticate on crates.io
+GitHub to complete this request. You may need to re-authenticate on [crates.io]
to grant permission to read GitHub org memberships. Just go to
https://crates.io/login
you will get the error above. You may also see this error if you ever try to
publish a crate that you don’t own at all, but otherwise happens to have a team.
-If you ever change your mind, or just aren’t sure if crates.io has sufficient
+If you ever change your mind, or just aren’t sure if [crates.io] has sufficient
permission, you can always go to https://crates.io/login, which will prompt you
-for permission if crates.io doesn’t have all the scopes it would like to.
+for permission if [crates.io] doesn’t have all the scopes it would like to.
An additional barrier to querying GitHub is that the organization may be
actively denying third party access. To check this, you can go to:
-Where you may choose to explicitly remove crates.io from your organization’s
+Where you may choose to explicitly remove [crates.io] from your organization’s
blacklist, or simply press the “Remove Restrictions” button to allow all third
party applications to access this data.
-Alternatively, when crates.io requested the `read:org` scope, you could have
-explicitly whitelisted crates.io querying the org in question by pressing
+Alternatively, when [crates.io] requested the `read:org` scope, you could have
+explicitly whitelisted [crates.io] querying the org in question by pressing
the “Grant Access” button next to its name:
# Is the plan to use GitHub as a package repository?
-No. The plan for Cargo is to use crates.io, like npm or Rubygems do with
+No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with
npmjs.org and rubygems.org.
We plan to support git repositories as a source of packages forever,
packages, including downloading from GitHub and copying packages into
your project itself.
-That said, we think that crates.io offers a number of important benefits, and
+That said, we think that [crates.io] offers a number of important benefits, and
will likely become the primary way that people download packages in Cargo.
For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a
# Can libraries use `*` as a version for their dependencies?
-**Starting January 22nd, 2016, crates.io will begin rejecting packages with
+**Starting January 22nd, 2016, [crates.io] will begin rejecting packages with
wildcard dependency constraints.**
While they _can_, strictly speaking, they should not. A version requirement
emphasize the ease of how a Cargo repository can be identified. An option of
many possible names has historically led to confusion where one case was handled
but others were accidentally forgotten.
+
+[crates.io]: https://crates.io/
% Specifying Dependencies
-Your crates can depend on other libraries from crates.io, git repositories, or
+Your crates can depend on other libraries from [crates.io], git repositories, or
subdirectories on your local file system. You can also temporarily override the
location of a dependency-- for example, to be able to test out a bug fix in the
dependency that you are working on locally. You can have different
# Specifying Dependencies from crates.io
-Cargo is configured to look for dependencies on `crates.io` by default. Only
+Cargo is configured to look for dependencies on [crates.io] by default. Only
the name and a version string are required in this case. In [the cargo
guide](guide.html), we specified a dependency on the `time` crate:
And that’s it! The next `cargo build` will automatically build `hello_utils` and
all of its own dependencies, and others can also start using the crate as well.
However, crates that use dependencies specified with only a path are not
-permitted on crates.io. If we wanted to publish our `hello_world` crate, we
-would need to publish a version of `hello_utils` to crates.io (or specify a git
+permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we
+would need to publish a version of `hello_utils` to [crates.io] (or specify a git
repository location) and specify its version in the dependencies line as well:
```toml
```
You’d like to have `conduit-static` use your local version of `conduit`,
-rather than the one on crates.io, while you fix the bug.
+rather than the one on [crates.io], while you fix the bug.
Cargo solves this problem by allowing you to have a local configuration
that specifies an **override**. If Cargo finds this configuration when
overridden. This path must be an absolute path.
Note: using a local configuration to override paths will only work for crates
-that have been published to crates.io. You cannot use this feature to tell Cargo
+that have been published to [crates.io]. You cannot use this feature to tell Cargo
how to find local unpublished crates.
More information about local configuration can be found in the [configuration
[target.'cfg(unix)'.dev-dependencies]
mio = "0.0.1"
```
+
+[crates.io]: https://crates.io/
projects / cargo.git / commitdiff